Quick Start. SLNG Basic API Instruction for Version 5.5 שרה אמנו 39/21 מודיעין I טל' I פקס

Transcription

1 Quick Start SLNG Basic API Instruction for Version 5.5 1

2 Contents Introduction... 4 Sending using HTTP JSON Post Interface... 5 Sending JSON format... 5 Fields Description Request... 6 Fields Description Response... 9 Sending Personalized message... 9 Example for sending using HTTP post HTTP Post PHP example HTTP Post C# example Get Message statistics using HTTP JSON Post Interface Get message statistics JSON format Fields Description Request Fields Description Response Example for getting message statistics using HTTP post HTTP Post PHP example HTTP Post C# example Delete, Add, Unsubscribe or Update contact profile using HTTP JSON Post Interface General command JSON format Fields Description Request Fields Description Response Fields Required/Optional per command Example for executing special command (delete contact) using HTTP post HTTP Post PHP example HTTP Post C# example Add, Deleted or Edit Group using HTTP JSON Post Interface General command JSON format Fields Description Request Fields Description Response Fields Required/Optional per command

3 Example for executing add new group command using HTTP post HTTP Post PHP example HTTP Post C# example Cancel /Sms Sending command using HTTP JSON Post Interface General command JSON format Fields Description Request Fields Description Response Fields Required/Optional per command Get user account balance using HTTP JSON Post Interface Get user balance command JSON format Fields Description Request Fields Description Response Example for executing special command (delete contact) using HTTP post HTTP Post PHP example HTTP Post C# example

4 Introduction This document is a quick start user guide for SLNG API application for sending . A separate document that can be found here described the SMS API. This document does not cover the complete API functionality but provide the most common use functionality, for further information please contact SLNG support team. Also please note that this document only described the JSON API that we recommend to use and as mentioned before for XML or web service interface please contact SLNG support team. In this document you can find detail instruction of the following topics: Http post Interface: 1. Sending using JSON HTTP post interface 2. Get message statistics using JSON HTTP post interface. 3. Unsubscribe contact using JSON HTTP POST interface. 4. Delete contact using JSON HTTP post interface. 5. Add new contact using JSON HTTP post interface. 6. Update contact profile using HTTP post interface 7. Get user account balance using HTTP post interface. 4

5 Sending using HTTP JSON Post Interface HTTP post request should be sent to the following URL with UTF-8 encoding in the HTTP post request body. Or (if SSL is needed) Sending JSON format Below JSON format described the sending command. As mentioned before the following JSON format should be sent in the request body of the HTTP call. Note that the HTML request must be sent with html and body tag. Request: "Username": "your API username", "Password": "your API password", "MsgName": "Your message name", "MsgBody": "Message body here", "FromName": "Sender name", "From ": "Sender ", "ReplyTo ": "Reply to ", "MsgBodyType": "message body type("1" for HTML format)", "LanguageType": "Language type ("1" for Hebrew)", "Subject": " subject", "MsgScheduleTime": "message schedule time (optional)", "GroupGUIDs": [ "Array of target group (GroupGUID) for this message", ], " s": [ " ": "contact ", "FirstName": "Contact first name", "LastName": "Contact last name", "Street": "Contact Street", "City": "Contact city", "Country": "Contact country", "PostalCode": "Contact postal code", "Fax": "Contact fax" ] 5

6 Response: Note that GeneralGUID field defines the MsgInfoGUID of the message and it use by some other command (for example, MsgInfoGUID field use to get the message statistics). "Status":true/false, "Description":"Command received successfully", "GeneralGUID":"xxxxxx" Fields Description Request Field Name Description Type Required/Optional Username your API username for SLNG system String Required Password your API password for SLNG system String Required MsgName Defines the message name that will present in SLNG system. String Required MsgBody Your message body. If you send HTML you HTML message has to include <html> and <body> tags. String Required FromName Defines the from name field. String Required From Defines the from field. String Required ReplyTo Define the reply to fileld. String Required MsgBodyType Define the message body type format: "1" HTML format "2" Text format String Required LanguageType Define the message language: "1" Hebrew "2' - English "3" Russia "4" - Arabic String Required Subject Define the message subject String Required 6

7 GroupGUIDs Define the target GroupGUID in SLNG for this message. Array of strings Optional only if s field below defined s Array of object that defines the contact profile fields. For more information see description of object below Array of object Optional only if GroupGUIDs field defined 7

8 Objet: object defined in the s fields of the message, as defined in the above field description table this object is optional if the GroupGUIDs field is defined. Please be aware of the following: 1. The contact object fields can be used to create a personalized message as described in the next section. 2. The number next to the field type (e.g: String(200)) defined the maximum string length of this field. Field Name Description Type Required/Optional Contact address. Note that this field is required only if the object defined. String Required FirstName Contact first name field. String (200) LastName Contact last name field. String (200) Street Contact street field. String (200) City Contact city field String (150) Country Contact country field. String (150) PostalCode Contact postal code field. String (20) Fax Contact Fax field. String (50) Optional Optional Optional Optional Optional Optional Optional 8

9 Fields Description Response Field Name Description Type Status Pass or Fail defines if the sending command pass or fail. Boolean Description Status description message String GeneralGUID Carries the message MsgInfoGUID field that use to get the message statistics String Sending Personalized message SLNG allow you to send a personalized message via the API interface. Personalized fields can be defined in the message body or in the subject. In the table below you can find the maximum length of each message and the format of the personalized field in the message body. Please also be aware that you can define your own fields if needed, for further information please contact SLNG support team. Field Name (API) Max length Field in Message ##שם_פרטי## 1 FirstName 200 ##FIRST_NAME## OR 2 LastName 200 ##שם_משפחה## ##LAST_NAME## OR 3 Street 200 ## רחוב## ##STREET## OR 4 City 150 ## עיר## ##CITY## OR 5 Country 150 ## מדינה## ##COUNTRY## OR 6 PostalCode 20 ##מיקוד## ##POSTAL_CODE## OR 7 Fax 50 ## פקס## ##FAX## OR 9

10 Example for sending using HTTP post HTTP Post PHP example <?php function Send Json () $url = " "; $json =' "Username": "xxxxxxx", "Password": "xxxxxxx", "MsgName": "Your message name", "MsgBody": "<html><head><title></title></head><body dir=\"rtl\"><p>this is a test</p></body></html ", "FromName": "SLNG Support", "From ": "test@test.co.il", "ReplyTo ": " test@test.co.il", "MsgBodyType": "1", "LanguageType": "1", "Subject": " subject", " s": [ " ": "test@test.co.il" ] '; // $CR = curl_init(); curl_setopt($cr, CURLOPT_URL, $url); curl_setopt($cr, CURLOPT_POST, 1); curl_setopt($cr, CURLOPT_FAILONERROR, true); curl_setopt($cr, CURLOPT_POSTFIELDS, $json); curl_setopt($cr, CURLOPT_RETURNTRANSFER, 1); curl_setopt($cr, CURLOPT_HTTPHEADER,array("charset=utf-8")); // $result = curl_exec($cr); $error = curl_error ($CR); $response = new SimpleXMLElement($result); TestApiJson();?> HTTP Post C# example Example below use Json.NET library to Serialize and De-serialize JSON objects. Json.NET library can be downloaded from the following link: 10

11 Further instruction about the installation of the package/library in Visual Studio environment can be found here: using Newtonsoft.Json;// Json.NET library public static bool Test ApiJson() string msg = System.Security.SecurityElement.Escape("<html><head><title></title></head><body dir=\"rtl\"><p>this is a test</p></body></html>"); List<string> dest = new List<string>(); dest .add("support@slng.co.il"); dest .add("shlomo@slng.co.il"); Send CmdJson obj = new Send CmdJson(); obj.username = "xxxxxxx; obj.password = "xxxxxxx"; obj.msgname = "Test SLNG API"; obj.msgbody = msg; obj.from = "support@slng.co.il"; obj.fromname = "SLNG Support"; obj.languagetype = "1"; obj.msgbodytype = "1"; obj.replyto = "suppoer@slng.co.il"; obj.subject = "Test "; obj.deliveryackurl = null; obj.highpriority = false; foreach (string in dest ) InfoJson obj1 = new InfoJson(); obj1. = ; obj1.firstname = "Shlomi"; obj1.lastname = "Haddad"; obj. s.add(obj1); string json = JsonConvert.SerializeObject(obj, Formatting.Indented); string json_enc = System.Web.HttpUtility.UrlEncode(json.ToString(), System.Text.Encoding.UTF8); ResponseJson obj2 = new ResponseJson(); obj2 = Post JsonDataToSLNG (" "SlngJson=" + json_enc); if (obj2.status) return true; else return false; 11

12 internal class InfoJson private string _ ; public string get return _ ; set _ = value; private string _AckID; public string AckID get return _AckID; set _AckID = value; value; value; private string _FirstName; public string FirstName get return _FirstName; set _FirstName = private string _LastName; public string LastName get return _LastName; set _LastName = private string _Street; public string Street get return _Street; set _Street = value; private string _City; public string City get return _City; set _City = value; value; private string _Country; public string Country get return _Country; set _Country = value; private string _PostalCode; public string PostalCode get return _PostalCode; set _PostalCode = private string _Fax; public string Fax get return _Fax; set _Fax = value; public InfoJson() this.ackid = null; this._ = null; this.firstname = null; this.lastname = null; this.city = null; this.country = null; this.fax = null; this.postalcode = null; this.street = null; internal class Send CmdJson private string _Username; public string Username get return _Username; set _Username = value; value; private string _Password; public string Password get return _Password; set _Password = private string _MsgName; 12

13 value; value; public string MsgName get return _MsgName; set _MsgName = value; private string _MsgBody; public string MsgBody get return _MsgBody; set _MsgBody = value; private string _FromName; public string FromName get return _FromName; set _FromName = private string _From ; public string From get return _From ; set _From = private string _ReplyTo ; public string ReplyTo get return _ReplyTo ; set _ReplyTo = value; private string _MsgBodyType; public string MsgBodyType get return _MsgBodyType; set _MsgBodyType = value; private string _LanguageType; public string LanguageType get return _LanguageType; set _LanguageType = value; private string _Subject; public string Subject get return _Subject; set _Subject = value; private string _DeliveryAckUrl; public string DeliveryAckUrl get return _DeliveryAckUrl; set _DeliveryAckUrl = value; private bool _HighPriority; public bool HighPriority get return _HighPriority; set _HighPriority = value; private List<string> _GroupGUIDs; public List<string> GroupGUIDs get return _GroupGUIDs; set _GroupGUIDs = value; private List< InfoJson> _ s; public List< InfoJson> s get return _ s; set _ s = value; public Send CmdJson() this.deliveryackurl = null; this.from = null; this.fromname = null; this.languagetype = null; this.msgbodytype = null; this.replyto = null; this._subject = null; this. s = new List< InfoJson>(); this.msgbody = null; 13

14 this.msgname = null; this.password = null; this.username = null; this.highpriority = false; this.groupguids = new List<string>(); public class ResponseJson private bool _Status; public bool Status get return _Status; set _Status = value; private string _Description; public string Description get return _Description; set _Description = value; private string _GeneralGUID; public string GeneralGUID get return _GeneralGUID; set _GeneralGUID = value; public ResponseJson() this.status = false; this.description = null; this.generalguid = null; public static ResponseJson Post JsonDataToSLNG(string url, string json) //Setup the web request string result = string.empty; WebRequest Request = WebRequest.Create(url); Request.Timeout = 30000; Request.Method = "POST"; Request.ContentType = "application/x-www-form-urlencoded"; //Set the POST data in a buffer byte[] xml_encoding; json = json.replace(" ", "+"); //Specify the length of the buffer xml_encoding = Encoding.UTF8.GetBytes(json); Request.ContentLength = xml_encoding.length; //Open up a request stream Stream RequestStream = Request.GetRequestStream(); //Write the POST data RequestStream.Write(xml_encoding, 0, xml_encoding.length); //Close the stream RequestStream.Close(); //Create the Response object WebResponse Response; Response = Request.GetResponse(); //Create the reader for the response StreamReader sr = new StreamReader(Response.GetResponseStream(), Encoding.UTF8); 14

15 //Read the response result = sr.readtoend(); //Close the reader, and response sr.close(); Response.Close(); string json_resp = System.Web.HttpUtility.UrlDecode(result); return JsonConvert.DeserializeObject< ResponseJson>(json_resp); ; 15

16 Get Message statistics using HTTP JSON Post Interface HTTP post request should be sent to the following URL with UTF-8 encoding in the HTTP post request body. Or (if SSL is needed) Get message statistics JSON format Below JSON format described the get message statistics command. As mentioned before the following JSON format should be sent in the request body. Note that MsgInfoGUID field return in the response object of sending command. Request JSON: "Username": "xxxxxxxxx", "Password": "xxxxxxxxx", "MsgInfoGUID": "xxxxxxxxx" Response JSON: "Pass": true, "Msg" :"Command completed successfully", "TotalContact":"5", "TotalSent":"5", "TotalOpen":"5", "TotalError":"0", "TotalReturn":"0", "TotalUnsubscribe":"0", "TotalClick":"0", "TotalContactClick":"0" 16

17 Fields Description Request Field Name Description Type Required/Optional Username your API username for SLNG system String Required Password your API password for SLNG system String Required MsgInfoGUID MsgInfoGUID field return from the sending command. String Required Fields Description Response Field Name Description Type Pass Return true or false value indicate the command status Boolean Msg Described the message status String TotalContact TotalSent Total number of contacts that associated with this message Total number of that sent (usually it should be equal to the total number of contacts unless the sending message is still in progress). String String TotalOpen Total contacts that open the message String TotalError Total error s in the list (hard error) String TotalReturn Total that sent but return (soft error) String TotalUnsubscribe Total unsubscribed contacts. String TotalClick Total clicks on the message String TotalContactClick Total contact that click on at list one link in the message String 17

18 Example for getting message statistics using HTTP post HTTP Post PHP example <?php function Send Json () $url = " GetMsgStatistics.ashx"; $json =' "Username": "xxxxxxxxx", "Password": "xxxxxxxxx", "MsgInfoGUID": "xxxxxxxxx" '; // $CR = curl_init(); curl_setopt($cr, CURLOPT_URL, $url); curl_setopt($cr, CURLOPT_POST, 1); curl_setopt($cr, CURLOPT_FAILONERROR, true); curl_setopt($cr, CURLOPT_POSTFIELDS, $json); curl_setopt($cr, CURLOPT_RETURNTRANSFER, 1); curl_setopt($cr, CURLOPT_HTTPHEADER,array("charset=utf-8")); // $result = curl_exec($cr); $error = curl_error ($CR); $response = new SimpleXMLElement($result); TestApiJson();?> HTTP Post C# example Example below use Json.NET library to Serialize and De-serialize JSON objects. Json.NET library can be downloaded from the following link: Further instruction about the installation of the package/library in Visual Studio environment can be found here: using Newtonsoft.Json;// Json.NET library public static bool TestGetMsgStatisticsApiJson() 18

19 MsgStatisticsReqJson obj = new MsgStatisticsReqJson(); MsgStatisticsResponseJson obj1 = new MsgStatisticsResponseJson(); obj.username = "xxxxxxxx"; obj.password = "xxxxxxxx"; obj.msginfoguid = "xxxxxxxxxxxxxxxxxx"; string json = JsonConvert.SerializeObject(obj, Formatting.Indented); string json_enc = System.Web.HttpUtility.UrlEncode(json.ToString(), System.Text.Encoding.UTF8); string json_resp; json_resp = PostJsonBodyDataToSLNG(" json_enc); obj1 = JsonConvert.DeserializeObject<MsgStatisticsResponseJson>(json_resp); if (obj1.pass) return true; else return false; internal class MsgStatisticsReqJson private string _Username; public string Username get return _Username; set _Username = value; value; private string _Password; public string Password get return _Password; set _Password = private string _MsgInfoGUID; public string MsgInfoGUID get return _MsgInfoGUID; set _MsgInfoGUID = value; public MsgStatisticsReqJson() this._username = null; this._password = null; this.msginfoguid = null; internal class MsgStatisticsResponseJson private bool _Pass; public bool Pass get return _Pass; set _Pass = value; private string _Msg; public string Msg get return _Msg; set _Msg = value; private string _TotalContact; public string TotalContact get return _TotalContact; set _TotalContact = value; 19

20 value; value; private string _TotalSent; public string TotalSent get return _TotalSent; set _TotalSent = private string _TotalOpen; public string TotalOpen get return _TotalOpen; set _TotalOpen = value; private string _TotalError; public string TotalError get return _TotalError; set _TotalError = private string _TotalReturn; public string TotalReturn get return _TotalReturn; set _TotalReturn = value; private string _TotalUnsubscribe; public string TotalUnsubscribe get return _TotalUnsubscribe; set _TotalUnsubscribe = value; value; private string _TotalClick; public string TotalClick get return _TotalClick; set _TotalClick = private string _TotalContactClick; public string TotalContactClick get return _TotalContactClick; set _TotalContactClick = value; public MsgStatisticsResponseJson() this._msg = null; this._pass = false; this._totalcontact = null; this.totalclick = null; this._totalcontactclick = null; this.totalerror = null; this.totalopen = null; this.totalreturn = null; this.totalsent = null; this.totalunsubscribe = null; public static string PostJsonBodyDataToSLNG(string url, string json) //Setup the web request string result = string.empty; WebRequest Request = WebRequest.Create(url); Request.Timeout = 30000; Request.Method = "POST"; Request.ContentType = "application/x-www-form-urlencoded"; //Set the POST data in a buffer 20

21 byte[] xml_encoding; json = json.replace(" ", "+"); //Specify the length of the buffer xml_encoding = Encoding.UTF8.GetBytes(json); Request.ContentLength = xml_encoding.length; //Open up a request stream Stream RequestStream = Request.GetRequestStream(); //Write the POST data RequestStream.Write(xml_encoding, 0, xml_encoding.length); //Close the stream RequestStream.Close(); //Create the Response object WebResponse Response; Response = Request.GetResponse(); //Create the reader for the response StreamReader sr = new StreamReader(Response.GetResponseStream(), Encoding.UTF8); //Read the response result = sr.readtoend(); //Close the reader, and response sr.close(); Response.Close(); string json_resp = System.Web.HttpUtility.UrlDecode(result); return json_resp; 21

22 Delete, Add, Unsubscribe or Update contact profile using HTTP JSON Post Interface This section described HTTP post request that use to delete, add, unsubscribe or update contact profile. As you can see in the section below the request command field defined the command that will be executed. HTTP post request should be sent to the following URL with UTF-8 encoding in the HTTP post request body. Or (if SSL is needed) General command JSON format Below JSON format described the general API JSON format for request and response call. As mentioned before the following JSON format should be sent in the request body. Note that for each command the table in the field section defined which fields are required. Request JSON: "Username": "xxxxxxxx", "Password": "xxxxxxxxxxxx", "Cmd": "DeleteContactCmd", "GroupGUIDs": [], "Mobile": "", " ": "FirstName": null, "LastName": null, "Street": null, "City": null, "Country": null, "PostalCode": null, "Fax": null 22

23 Response JSON: "Pass": true or false, "Msg":"Staus description", Fields Description Request Please note that the number next to the field type (e.g: String(200)) defined the maximum string length of this field. Field Name Description Type Username your API username for SLNG system String Password your API password for SLNG system String Cmd GroupGUIDs Mobile Valid command are: (1) DeleteContactCmd (2) UnsubscribeContactCmd (3) AddContactCmd (4) UpdateContactProfileCmd Define the target group for new contact, if not defined new contact will be added to the default group (optional for AddContactCmd and not needed for all other commands) Contact mobile number (optional only if address defined) Contact address (optional only if mobile number defined) String Array of string String String FirstName Contact first name String (200) LastName Contact last name String (200) Street Contact street name String (200) 23

24 City Contact city name String (150) Country Contact country String (150) PostalCode Contact postal code String (20) Fax Contact fax number String (50) Fields Description Response Field Name Description Type Pass Return true or false value indicate the command status Boolean Msg Described the message status String Fields Required/Optional per command Table below described required, optional or not needed for each request command. Field Name DeleteContactCmd UnsubscribeContactCmd AddContactCmd UpdateContactProfileCmd Username required required required required Password required required required required Cmd required required required required GroupGUIDs not needed not needed optional not needed Mobile required ( or mobile required) required ( or mobile required) required ( or mobile required) required ( or mobile required) 24

25 required ( or mobile required) required ( or mobile required) required ( or mobile required) required ( or mobile required) FirstName not needed not needed optional optional LastName not needed not needed optional optional Street not needed not needed optional optional City not needed not needed optional optional Country not needed not needed optional optional PostalCode not needed not needed optional optional Fax not needed not needed optional optional Example for executing special command (delete contact) using HTTP post HTTP Post PHP example <?php function Send Json () $url = " $json =' "Username": "xxxxxxxx", "Password": "xxxxxxxxxxxx", "Cmd": "DeleteContactCmd", " ": "test_api1234@slng.co.il" '; // $CR = curl_init(); curl_setopt($cr, CURLOPT_URL, $url); curl_setopt($cr, CURLOPT_POST, 1); curl_setopt($cr, CURLOPT_FAILONERROR, true); curl_setopt($cr, CURLOPT_POSTFIELDS, $json); curl_setopt($cr, CURLOPT_RETURNTRANSFER, 1); curl_setopt($cr, CURLOPT_HTTPHEADER,array("charset=utf-8")); // $result = curl_exec($cr); $error = curl_error ($CR); $response = new SimpleXMLElement($result); TestApiJson();?> 25

26 6.6.2 HTTP Post C# example Example below use Json.NET library to Serialize and De-serialize JSON objects. Json.NET library can be downloaded from the following link: Further instruction about the installation of the package/library in Visual Studio environment can be found here: using Newtonsoft.Json;// Json.NET library public static bool TestApiGeneralCmdJson() ApiGeneralCmdReqJSON obj = new ApiGeneralCmdReqJSON(); ApiGeneralCmdResponseJSON obj1 = new ApiGeneralCmdResponseJSON(); obj.username = "xxxxxxx"; obj.password = "xxxxxxxxx"; obj. = "test_api1234@slng.co.il"; obj.mobile = ""; obj.firstname = "API FIRST NAME TEST"; obj.lastname = "API LAST NAME TEST"; obj.cmd = "DeleteContactCmd"; string json = JsonConvert.SerializeObject(obj, Formatting.Indented); string json_enc = System.Web.HttpUtility.UrlEncode(json.ToString(), System.Text.Encoding.UTF8); string json_resp; json_resp = PostJsonBodyDataToSLNG(" json_enc); obj1 = JsonConvert.DeserializeObject<ApiGeneralCmdResponseJSON>(json_resp); if (obj1.pass) return true; else return false; internal class ApiGeneralCmdResponseJSON private bool _Pass; public bool Pass get return _Pass; set _Pass = value; 26

27 private string _Msg; public string Msg get return _Msg; set _Msg = value; public ApiGeneralCmdResponseJSON() this.pass = false; this._msg = null; internal class ApiGeneralCmdReqJSON private string _Username; public string Username get return _Username; set _Username = value; value; private string _Password; public string Password get return _Password; set _Password = private string _Cmd; public string Cmd get return _Cmd; set _Cmd = value; private List<string> _GroupGUIDs; public List<string> GroupGUIDs get return _GroupGUIDs; set _GroupGUIDs = value; private string _Mobile; public string Mobile get return _Mobile; set _Mobile = value; private string _ ; public string get return _ ; set _ = value; value; value; private string _FirstName; public string FirstName get return _FirstName; set _FirstName = private string _LastName; public string LastName get return _LastName; set _LastName = private string _Street; public string Street get return _Street; set _Street = value; private string _City; public string City get return _City; set _City = value; value; private string _Country; public string Country get return _Country; set _Country = value; private string _PostalCode; public string PostalCode get return _PostalCode; set _PostalCode = private string _Fax; public string Fax get return _Fax; set _Fax = value; 27

28 public ApiGeneralCmdReqJSON() this._username = null; this._password = null; this._cmd = null; this. = null; this.mobile = null; this.firstname = null; this.lastname = null; this.city = null; this.country = null; this.fax = null; this.postalcode = null; this.street = null; this.groupguids = new List<string>(); public static string PostJsonBodyDataToSLNG(string url, string json) //Setup the web request string result = string.empty; WebRequest Request = WebRequest.Create(url); Request.Timeout = 30000; Request.Method = "POST"; Request.ContentType = "application/x-www-form-urlencoded"; //Set the POST data in a buffer byte[] xml_encoding; json = json.replace(" ", "+"); //Specify the length of the buffer xml_encoding = Encoding.UTF8.GetBytes(json); Request.ContentLength = xml_encoding.length; //Open up a request stream Stream RequestStream = Request.GetRequestStream(); //Write the POST data RequestStream.Write(xml_encoding, 0, xml_encoding.length); //Close the stream RequestStream.Close(); //Create the Response object WebResponse Response; Response = Request.GetResponse(); //Create the reader for the response StreamReader sr = new StreamReader(Response.GetResponseStream(), Encoding.UTF8); //Read the response result = sr.readtoend(); //Close the reader, and response sr.close(); Response.Close(); string json_resp = System.Web.HttpUtility.UrlDecode(result); return json_resp; 28

29 Add, Deleted or Edit Group using HTTP JSON Post Interface This section described HTTP post request that use to delete, add or edit groups. As you can see in the section below the request command field defined the command that will be executed. HTTP post request should be sent to the following URL with UTF-8 encoding in the HTTP post request body. Or (if SSL is needed) General command JSON format Below JSON format described the general API JSON format for request and response call. As mentioned before the following JSON format should be sent in the request body. Note that for each command the table in the field section defined which fields are required. Request JSON: "Username": "xxxxxxxx", "Password": "xxxxxxxxxxxx", "Cmd": " AddNewGroup", "GroupGUIDs": [], "GroupName": "New group name" Response JSON: "Pass": true or false, "Msg":"Staus description" Fields Description Request Please note that the number next to the field type (e.g: String(200)) defined the maximum string length of this field. 29

30 Field Name Description Type Username your API username for SLNG system String Password your API password for SLNG system String Cmd GroupGUIDs GroupName Valid command are: (1) AddNewGroup (2) DeleteGroup (3) EditGroupName Define the group GUID field for editing or deleting group. (optional for AddNewGroup ). Note that only the first item in the array is valid and there is no option for example to dlete multi groups in one command. Define the group name filed needed for edit group name command and add new group command. String Array of string String (100) Fields Description Response Field Name Description Type Pass Return true or false value indicate the command status Boolean Msg Described the message status String Fields Required/Optional per command Table below described required, optional or not needed for each request command. Field Name AddNewGroup DeleteGroup EditGroupName Username required required required Password required required required Cmd required required required 30

31 GroupGUIDs not needed required required GroupName required Not needed required Example for executing add new group command using HTTP post HTTP Post PHP example <?php function Send Json () $url = " $json =' "Username": "xxxxxxxx", "Password": "xxxxxxxxxxxx", "Cmd": " AddNewGroup", "GroupName": "NEW GROUP FROM API" '; // $CR = curl_init(); curl_setopt($cr, CURLOPT_URL, $url); curl_setopt($cr, CURLOPT_POST, 1); curl_setopt($cr, CURLOPT_FAILONERROR, true); curl_setopt($cr, CURLOPT_POSTFIELDS, $json); curl_setopt($cr, CURLOPT_RETURNTRANSFER, 1); curl_setopt($cr, CURLOPT_HTTPHEADER,array("charset=utf-8")); // $result = curl_exec($cr); $error = curl_error ($CR); $response = new SimpleXMLElement($result); TestApiJson();?> HTTP Post C# example Example below use Json.NET library to Serialize and De-serialize JSON objects. Json.NET library can be downloaded from the following link: 31

32 Further instruction about the installation of the package/library in Visual Studio environment can be found here: using Newtonsoft.Json;// Json.NET library public static bool TestApiAddGroupGeneralCmdJson() ApiGeneralGroupCmdReqJSON obj = new ApiGeneralGroupCmdReqJSON(); ApiGeneralCmdResponseJSON obj1 = new ApiGeneralCmdResponseJSON(); obj.username = "xxxxxxx"; obj.password = "xxxxxxxxx"; obj.groupname = "NEW GROUP FROM API"; obj.cmd = "AddNewGroup"; string json = JsonConvert.SerializeObject(obj, Formatting.Indented); string json_enc = System.Web.HttpUtility.UrlEncode(json.ToString(), System.Text.Encoding.UTF8); string json_resp; json_resp = PostJsonBodyDataToSLNG(" json_enc); obj1 = JsonConvert.DeserializeObject<ApiGeneralCmdResponseJSON>(json_resp); if (obj1.pass) return true; else return false; internal class ApiGeneralCmdResponseJSON private bool _Pass; public bool Pass get return _Pass; set _Pass = value; private string _Msg; public string Msg get return _Msg; set _Msg = value; public ApiGeneralCmdResponseJSON() this.pass = false; this._msg = null; internal class ApiGeneralGroupCmdReqJSON private string _Username; public string Username get return _Username; set _Username = value; private string _Password; 32

33 value; public string Password get return _Password; set _Password = private string _Cmd; public string Cmd get return _Cmd; set _Cmd = value; private List<string> _GroupGUIDs; public List<string> GroupGUIDs get return _GroupGUIDs; set _GroupGUIDs = value; private string _GroupName; public string GroupName get return _GroupName; set _GroupName = value; public ApiGeneralGroupCmdReqJSON() this._username = null; this._password = null; this._cmd = null; this.groupguids = new List<string>(); this.groupname = null; public static string PostJsonBodyDataToSLNG(string url, string json) //Setup the web request string result = string.empty; WebRequest Request = WebRequest.Create(url); Request.Timeout = 30000; Request.Method = "POST"; Request.ContentType = "application/x-www-form-urlencoded"; //Set the POST data in a buffer byte[] xml_encoding; json = json.replace(" ", "+"); //Specify the length of the buffer xml_encoding = Encoding.UTF8.GetBytes(json); Request.ContentLength = xml_encoding.length; //Open up a request stream Stream RequestStream = Request.GetRequestStream(); //Write the POST data RequestStream.Write(xml_encoding, 0, xml_encoding.length); //Close the stream RequestStream.Close(); //Create the Response object WebResponse Response; Response = Request.GetResponse(); //Create the reader for the response StreamReader sr = new StreamReader(Response.GetResponseStream(), Encoding.UTF8); //Read the response result = sr.readtoend(); //Close the reader, and response sr.close(); Response.Close(); string json_resp = System.Web.HttpUtility.UrlDecode(result); return json_resp; 33

34 Cancel /Sms Sending command using HTTP JSON Post Interface This section described HTTP post request that allow to cancel sending command that already sent and schedule for future time. HTTP post request should be sent to the following URL with UTF-8 encoding in the HTTP post request body. Or (if SSL is needed) General command JSON format Below JSON format described the general API JSON format for request and response call. As mentioned before the following JSON format should be sent in the request body. Note that for each command the table in the field section defined which fields are required. Request JSON: "Username": "xxxxxxxx", "Password": "xxxxxxxxxxxx", "Cmd": "CancelSendingCommand", "MsgInfoGUID": "(received from the sending command)" Response JSON: "Pass": true or false, "Msg":"Staus description" Fields Description Request Field Name Description Type Username your API username for SLNG system String 34

35 Password your API password for SLNG system String Cmd MsgInfoGUID Valid command are: (1) CancelSendingCommand Define the MsgInfoGUID field that rerun from the sending command. String String Fields Description Response Field Name Description Type Pass Return true or false value indicate the command status Boolean Msg Described the message status String Fields Required/Optional per command Table below described required, optional or not needed for each request command. Field Name Username Password Cmd MsgInfoGUID CancelSendingCommand required required required required 35

36 36

37 Get user account balance using HTTP JSON Post Interface This section described the HTTP post request for getting the user account balance. HTTP post request should be sent to the following URL with UTF-8 encoding in the HTTP post request body. Or (if SSL is needed) Get user balance command JSON format Below JSON format described the general API JSON format for get user balance command. As mentioned before the following JSON format should be sent in the request body. Request JSON: "Username": "xxxxxxxx", "Password": "xxxxxxxxxxxx", Response JSON:. "Pass": true or false, "Msg":"Staus description", "QtySms": "100", "Qty ":"100"", Fields Description Request Field Name Description Type Username your API username for SLNG system String Password your API password for SLNG system String 37

38 Fields Description Response Field Name Description Type Pass Return true or false value indicate the command status Boolean Msg Described the message status String QtySms Total number of available SMS in the account String Qty Total number of available in the account String Example for executing special command (delete contact) using HTTP post HTTP Post PHP example <?php function Send Json () $url = " GetUserBalanceJson.ashx"; $json =' "Username": "xxxxxxxx", "Password": "xxxxxxxxxxxx", '; // $CR = curl_init(); curl_setopt($cr, CURLOPT_URL, $url); curl_setopt($cr, CURLOPT_POST, 1); curl_setopt($cr, CURLOPT_FAILONERROR, true); curl_setopt($cr, CURLOPT_POSTFIELDS, $json); curl_setopt($cr, CURLOPT_RETURNTRANSFER, 1); curl_setopt($cr, CURLOPT_HTTPHEADER,array("charset=utf-8")); // $result = curl_exec($cr); $error = curl_error ($CR); $response = new SimpleXMLElement($result); TestApiJson();?> 38

39 HTTP Post C# example Example below use Json.NET library to Serialize and De-serialize JSON objects. Json.NET library can be downloaded from the following link: Further instruction about the installation of the package/library in Visual Studio environment can be found here: using Newtonsoft.Json;// Json.NET library public static bool TestGetUserBalanceApiJson() UserBalanceCmdJson obj = new UserBalanceCmdJson(); UserBalanceResponseJson obj1 = new UserBalanceResponseJson(); obj.username = "xxxxx"; obj.password = "xxxxxxx"; string json = JsonConvert.SerializeObject(obj, Formatting.Indented); string json_enc = System.Web.HttpUtility.UrlEncode(json.ToString(), System.Text.Encoding.UTF8); string json_resp; json_resp = PostJsonBodyDataToSLNG(" json_enc); obj1 = JsonConvert.DeserializeObject<UserBalanceResponseJson>(json_resp); if (obj1.pass) return true; else return false; internal class UserBalanceCmdJson private string _Username; public string Username get return _Username; set _Username = value; value; private string _Password; public string Password get return _Password; set _Password = public UserBalanceCmdJson() 39

40 this.password = null; this.username = null; internal class UserBalanceResponseJson private bool _Pass; public bool Pass get return _Pass; set _Pass = value; private string _Msg; public string Msg get return _Msg; set _Msg = value; value; private string _Qty ; public string Qty get return _Qty ; set _Qty = private string _QtySms; public string QtySms get return _QtySms; set _QtySms = value; public UserBalanceResponseJson() this._msg = null; this._pass = false; this.qty = null; this.qtysms = null; public static string PostJsonBodyDataToSLNG(string url, string json) //Setup the web request string result = string.empty; WebRequest Request = WebRequest.Create(url); Request.Timeout = 30000; Request.Method = "POST"; Request.ContentType = "application/x-www-form-urlencoded"; //Set the POST data in a buffer byte[] xml_encoding; json = json.replace(" ", "+"); //Specify the length of the buffer xml_encoding = Encoding.UTF8.GetBytes(json); Request.ContentLength = xml_encoding.length; //Open up a request stream Stream RequestStream = Request.GetRequestStream(); //Write the POST data RequestStream.Write(xml_encoding, 0, xml_encoding.length); 40

41 //Close the stream RequestStream.Close(); //Create the Response object WebResponse Response; Response = Request.GetResponse(); //Create the reader for the response StreamReader sr = new StreamReader(Response.GetResponseStream(), Encoding.UTF8); //Read the response result = sr.readtoend(); //Close the reader, and response sr.close(); Response.Close(); string json_resp = System.Web.HttpUtility.UrlDecode(result); return json_resp; 41